Get Subscriber Offer

This API is used to retrieve SIM card plans and their details at two levels:

Plans attached by the parent account to the SIM and paid by the current account to the parent
Plans attached by the current account to its sub-account (customer) paid by the customer to the current account

HTTP URL
GET	/api/v2/subscriber/{type}/{value}/offer

NOTE: All {type} and {value} pairs, define the search criteria. Valid {type} ENUMs are: ‘imsi’, ‘iccid’, ‘msisdn’, ‘imei’.

Eligibility

The Requester is eligible to request plan information on self (attached by the parent account) and plan information on sub-accounts (customers).

API Request

This API has no request structure.

API Response

Response Structure

Parameter	Type	M/O/CM	Description
errorCode	String	O	Failure code.
errorMessage	String	O	Failure message.
content	Object	O	Array of main response body object displayed when an API call was successful. For a failure, it will be empty.
pageable	Object	O	Paging information object displayed when an API call was successful. For a failure, it will be empty.

Content data objects

Element	Type	M/O/CM	Description
id	UUID	M	Offer instance attached to the subscriber
name	String	M	Offer name
description	String	O	Offer description
type	String	M	Offer type. ENUM: USAGE, MONEY, RATE
renewalDate	Date	O	Offer next renewal date
expirationDate	Date	O	Offer expiration date
subscriberId	UUID	M	Subscriber universal unique identifier
customerId	UUID	M	Customer ID
customerName	String	M	Customer name
cost	Decimal	O	Offer cost of Money or Usage plan types.Rate: Future feature. Currently empty
currency	String	CM	Cost currency.Monetary: for example, USD, GBP, EUR
attachTimestamp	DateTime	O	Attach offer timestamp. Format: YYYY-MM-DD HH:MI:SS.ms
priority	Numeric	M	Plan consumption order
isIncludingAccessFee	Boolean	M	Specifies if the offer price already includes inherent access Specifies if the offer price already includes inherent access fee and surcharge fee. True – Offer price includes access\surcharge fees. Once a calendar month, when registering on the network, the system will not charge additionally on top of the offer price. False – Offer price does not include access\surcharge fee. Once a calendar month, when registering on the network, the system will charge the access\surcharge fees in addition to the offer price.
balance	Object	M	Array of balances object
usage	Object	O	Array of usage object
availabilityZone			Array of availability zones object which are assigned to this plan instance. Empty array means that the plan instance is available in any zone.
linkedOffers	Object	M	Array of offer(s) object that is linked to this offer. The order of the instances in the array determines their priority for charging.

Balance data objects

Element	Type	M/O/CM	Description
id	UUID	M	Balance Universal Unique ID
service	String	CM	Service type. Mandatory for usage plan. ENUM: DATA, SMS
currency	String	M	If monetary, then provide the currency. For example, USD, GBP, EURIf usage, then provide the currency by usage type. ENUM: SMS Data: KB, MB, GB
value	Decimal	O	Balance value
creditLimit	Decimal	O	Usage limit

Usage data objects

Parameter	Type	M/O/CM	Description
service	String	CM	Service type. ENUM valid values: DATA, SMS Mandatory when there is a usage consumption
currency	String	CM	Usage currency by usage type. ENUM: SMS - SMS, Data - KB, MB, GB Mandatory when ‘usage service’ attribute is filled in.
value	Decimal	O	Balance value

availabilityZone

Parameter	Type	M/O/CM	Description
Id	UUID	M	Customer’s availability zone’s universal unique identity
name	String	M	Customer’s availability zone name
description	String	O	Customer’s availability zone description
zone	Object	M	Array of Zone Object

zone

Parameter	Type	M/O/CM	Description
Id	UUID	M	Customer zone’s universal unique identity
name	String	M	Customer zone name
countryCode	String	M	ISO alpha-3 Country Code
network	Object	M	Array of Mobile Network object

network

Parameter	Type	M/O/CM	Description
plmn	String	M	Public Land Mobile Network. MCCMNC representation
mcc	String	M	Mobile Country Code (MCC)
mnc	String	M	Mobile Network Code (MNC)

linkedOffers

Element	Type	M/O/CM	Description
id	UUID	M	Universal unique ID of the offer to link to this offer
isPinned	Boolean	M	Denotes whether or not the linked offer can be removed from this offer. True = Linked offer is fixed and cannot be removed. False = Linked offer is not fixed and can be removed (Future Feature)

Pageable data objects

Element	Type	M/O/CM	Description
page	Numeric	M	Page number
size	Numeric	M	Page size. Number of requested elements per page
totalPages	Numeric	M	Total amount of available pages per requested page size
totalElements	Numeric	M	Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code	Message
GLOBAL_1001	Service unavailable. Please try again
SUBSCRIBER_1002	Subscriber does not exist
SUBSCRIBER_1006	Failed to retrieve subscriber details

Examples

Request Body

Copy

{
}

Response Body: Success ACK

Copy

{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "roaming 20GB",
      "description": "roaming offer 20 GB",
      "type": "USAGE",
      "renewalDate": "23122023",
      "expirationDate": "23052024",
      "subscriberId": "46251e2b-c029-4b1f-b053-47f31a2175d9",
      "customerId": "d3fcef24-5c13-41ed-9d33-995b7d5f45a6",
      "customerName": "Gualas",
      "cost": 20.5,
      "currency": "EUR",
      "attachTimestamp": "2020-11-11 08:47:46.758866",
      "priority": 100,
      "isIncludingAccessFee": false,
      "balance": [
        {
          "id": "69b431f7-e885-4a7c-9539-ac1de961fb7f",
          "service": "DATA",
          "currency": "KB",
          "value": 100,
          "creditLimit": 20
        }
      ],
      "usage": [
        {
          "service": "DATA",
          "currency": "KB",
          "value": 20
        }
      ],
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05",
          "description": "All Canadian regions and north USA region",
          "zone": [
            {
              "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
              "name": "All Canada",
              "countryCode": "CAN",
              "network": [
                {
                  "plmn": "CANTS",
                  "mcc": "302",
                  "mnc": "220"
                },
                {
                  "plmn": "CANVT",
                  "mcc": "302",
                  "mnc": "500"
                }
              ]
            },
            {
              "id": "ceb892d2-f24b-4007-bf81-999fe75cb635",
              "name": "North USA",
              "countryCode": "GBR",
              "network": [
                {
                  "plmn": "GBRME",
                  "mcc": "234",
                  "mnc": "30"
                },
                {
                  "plmn": "GBRVF",
                  "mcc": "234",
                  "mnc": "15"
                },
                {
                  "plmn": "AAM26",
                  "mcc": "901",
                  "mnc": "46"
                }
              ]
            }
          ]
        }
      ],
      "linkedOffers": [
        {
          "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
          "isPinned": true
        },
        {
          "id": "ff74dba6-8e7f-4b15-a42b-13810913b371",
          "isPinned": true
        }
      ]
    },
    {
      "id": "e35977e8-719d-4df7-9803-8e75e7bab61c",
      "name": "data 10GB",
      "description": "data offer 20 GB",
      "type": "USAGE",
      "renewalDate": "23122023",
      "expirationDate": "23052024",
      "subscriberId": "e1552d9f-5aa8-4958-9156-59e4878b6cc0",
      "customerId": "89af6bfe-56bf-47d0-a3dd-a983e940fd4d",
      "customerName": "Gualas",
      "cost": 20.5,
      "currency": "EUR",
      "attachTimestamp": "2020-11-11 08:47:46.758866",
      "priority": 100,
      "isIncludingAccessFee": true,
      "balance": [
        {
          "id": "ceb892d2-f24b-4007-bf81-999fe75cb635",
          "service": "DATA",
          "currency": "KB",
          "value": 100,
          "creditLimit": 20
        }
      ],
      "usage": [
        {
          "service": "SMS",
          "currency": "SMS",
          "value": 20
        }
      ],
      "availabilityZone": null,
      "linkedOffers": [
        {
          "id": "ea73dcc6-6c7f-4c65-a42c-13560913c330",
          "isPinned": true
        },
        {
          "id": "ff74dba6-8e7f-4b15-a42b-13810913b371",
          "isPinned": true
        }
      ]
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1

Response Body: Failure NAK

Copy

{
  "errorCode": "SUBSCRIBER_1006",
  "errorMessage": "Failed to retrieve subscriber details",
  "content": "",
  "pageable": ""
}